From 7972dc877634ee6f57e3b0f2d2f20a2c333d090f Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Mon, 3 Aug 2020 17:42:05 -0400 Subject: [PATCH] docs: Unify docs around incremental operations Sync up the wording around incremental filtering and sorting to be more similar. --- gtk/gtkfilterlistmodel.c | 8 ++++++-- gtk/gtksortlistmodel.c | 12 ++++++++++-- 2 files changed, 16 insertions(+), 4 deletions(-) diff --git a/gtk/gtkfilterlistmodel.c b/gtk/gtkfilterlistmodel.c index 52d3c860d9..9d943fb2ae 100644 --- a/gtk/gtkfilterlistmodel.c +++ b/gtk/gtkfilterlistmodel.c @@ -786,6 +786,9 @@ gtk_filter_list_model_get_model (GtkFilterListModel *self) * interesting around 10,000 to 100,000 items. * * By default, incremental filtering is disabled. + * + * See gtk_filter_list_model_get_pending() for progress information + * about an ongoing incremental filtering operation. **/ void gtk_filter_list_model_set_incremental (GtkFilterListModel *self, @@ -837,8 +840,6 @@ gtk_filter_list_model_get_incremental (GtkFilterListModel *self) * * Returns the number of items that have not been filtered yet. * - * When incremental filtering is not enabled, this always returns 0. - * * You can use this value to check if @self is busy filtering by * comparing the return value to 0 or you can compute the percentage * of the filter remaining by dividing the return value by the total @@ -850,6 +851,9 @@ gtk_filter_list_model_get_incremental (GtkFilterListModel *self) * percentage = pending / (double) g_list_model_get_n_items (model); * ]| * + * If no filter operation is ongoing - in particular when + * #GtkFilterListModel:incremental is %FALSE - this function returns 0. + * * Returns: The number of items not yet filtered **/ guint diff --git a/gtk/gtksortlistmodel.c b/gtk/gtksortlistmodel.c index 24c2b5271d..8f758d46cf 100644 --- a/gtk/gtksortlistmodel.c +++ b/gtk/gtksortlistmodel.c @@ -61,6 +61,10 @@ * #GtkSortListModel is a list model that takes a list model and * sorts its elements according to a #GtkSorter. * + * The model can be set up to do incremental sorting, so that + * sorting long lists doesn't block the UI. See + * gtk_sort_list_model_set_incremental() for details. + * * #GtkSortListModel is a generic model and because of that it * cannot take advantage of any external knowledge when sorting. * If you run into performance issues with #GtkSortListModel, it @@ -978,6 +982,9 @@ gtk_sort_list_model_get_sorter (GtkSortListModel *self) * interesting around 10,000 to 100,000 items. * * By default, incremental sorting is disabled. + * + * See gtk_sort_list_model_get_pending() for progress information + * about an ongoing incremental sorting operation. */ void gtk_sort_list_model_set_incremental (GtkSortListModel *self, @@ -1032,8 +1039,9 @@ gtk_sort_list_model_get_incremental (GtkSortListModel *self) * * If you want to estimate the progress, you can use code like this: * |[ - * double progress = 1.0 - (double) gtk_sort_list_model_get_pending (self) - * / MAX (1, g_list_model_get_n_items (G_LIST_MODEL (sort))); + * pending = gtk_sort_list_model_get_pending (self); + * model = gtk_sort_list_model_get_model (self); + * progress = 1.0 - pending / (double) MAX (1, g_list_model_get_n_items (model)); * ]| * * If no sort operation is ongoing - in particular when -- 2.30.2